<!-- HTML header for doxygen 1.9.7-->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en-US">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.13.2"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<title>libsir: The Standard Incident Reporter Library</title>
<!-- OpenGraph -->
<meta property="og:title" content="libsir: The Standard Incident Reporter Library">
<meta property="og:description" content="A lightweight, cross-platform C library for information distribution">
<meta property="og:url" content="https://libsir.rml.dev">
<meta property="og:type" content="website">
<meta property="og:image" content="https://libsir.rml.dev/res/libsir-og.png">
<meta name="twitter:card" content="summary_large_image"></meta>
<meta name="twitter:title" content="libsir: The Standard Incident Reporter Library"></meta>
<meta name="twitter:description" content="A lightweight, cross-platform C library for information distribution"></meta>
<meta name="twitter:image" content="https://libsir.rml.dev/res/libsir-og.png"></meta>
<!-- /OpenGraph -->
<!-- favicon -->
<link rel="icon" href="res/libsir-icon.png">
<link rel="icon" href="res/libsir-icon.svg" type="image/svg+xml">
<link rel="manifest" href="res/icons.webmanifest">
<!-- /favicon -->
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="cookie.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="stylesheet.css" rel="stylesheet" type="text/css" />
<link href="rml-navtree.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr id="projectrow">
  <td id="projectalign">
   <div id="projectname">libsir<span id="projectnumber">&#160;2.2.6</span>
   </div>
   <div id="projectbrief">Standard Incident Reporter</div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.13.2 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
var searchBox = new SearchBox("searchBox", "search/",'.html');
/* @license-end */
</script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(function() { codefold.init(0); });
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(function() {
  initMenu('',true,false,'search.php','Search',true);
  $(function() { init_search(); });
});
/* @license-end */
</script>
<div id="main-nav"></div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(function(){initNavTree('index.html',''); initResizable(true); });
/* @license-end */
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<div id="MSearchResults">
<div class="SRPage">
<div id="SRIndex">
<div id="SRResults"></div>
<div class="SRStatus" id="Loading">Loading...</div>
<div class="SRStatus" id="Searching">Searching...</div>
<div class="SRStatus" id="NoMatches">No Matches</div>
</div>
</div>
</div>
</div>

<div><div class="header">
  <div class="headertitle"><div class="title">libsir </div></div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p><a class="anchor" id="md__r_e_a_d_m_e"></a></p>
<p>libsir&mdash;a lightweight, cross-platform library for information distribution</p>
<p><a href="https://github.com/aremmell/libsir/releases/latest"><img src="https://img.shields.io/github/v/release/aremmell/libsir?color=%2340b900&amp;cacheSeconds=60" alt="Release" class="inline"/></a> <a href="https://github.com/aremmell/libsir/commits/master"><img src="https://img.shields.io/github/commits-since/aremmell/libsir/latest?cacheSeconds=60&amp;color=%2340b900" alt="Commits" class="inline"/></a> <a href="https://github.com/aremmell/libsir/blob/master/LICENSE"><img src="https://img.shields.io/github/license/aremmell/libsir?color=%2340b900&amp;cacheSeconds=60" alt="License" class="inline"/></a> <a href="https://www.openhub.net/p/libsir/"><img src="https://img.shields.io/badge/openhub-libsir-ok.svg?color=%2340b900&amp;cacheSeconds=60" alt="OpenHub" style="pointer-events: none;" class="inline"/></a> <a href="https://gitlab.com/libsir/libsir/pipelines/master/latest"><img src="https://gitlab.com/libsir/libsir/badges/master/pipeline.svg?" alt="GitLab" style="pointer-events: none;" class="inline"/></a> <a href="https://coveralls.io/github/aremmell/libsir"><img src="https://img.shields.io/coverallsCoverage/github/aremmell/libsir?color=%2340b900&amp;cacheSeconds=60" alt="Coverage" class="inline"/></a> <a href="https://scan.coverity.com/projects/aremmell-libsir"><img src="https://img.shields.io/coverity/scan/28843.svg?color=%2340b900&amp;cacheSeconds=60" alt="Coverity" style="pointer-events: none;" class="inline"/></a> <a href="https://api.reuse.software/info/github.com/aremmell/libsir"><img src="https://img.shields.io/reuse/compliance/github.com%2Faremmell%2Flibsir?label=REUSE3&amp;color=%2340b900&amp;cacheSeconds=60" alt="REUSE" class="inline"/></a> <a href="https://sonarcloud.io/component_measures?id=aremmell_libsir&amp;metric=new_maintainability_rating&amp;view=list"><img src="https://sonarcloud.io/api/project_badges/measure?project=aremmell_libsir&amp;metric=sqale_rating" alt="Maintainability" class="inline"/></a> <a href="https://sonarcloud.io/component_measures?id=aremmell_libsir&amp;metric=new_reliability_rating&amp;view=list"><img src="https://sonarcloud.io/api/project_badges/measure?project=aremmell_libsir&amp;metric=reliability_rating" alt="Reliability" class="inline"/></a> <a href="https://sonarcloud.io/component_measures?id=aremmell_libsir&amp;metric=new_security_rating&amp;view=list"><img src="https://sonarcloud.io/api/project_badges/measure?project=aremmell_libsir&amp;metric=security_rating" alt="Security" class="inline"/></a> <a href="https://securityscorecards.dev/viewer/?uri=github.com/aremmell/libsir"><img src="https://img.shields.io/ossf-scorecard/github.com/aremmell/libsir?label=openssf%20scorecard&amp;style=flat&amp;color=%2340b900&amp;cacheSeconds=60" alt="Scorecard" class="inline"/></a> <a href="https://www.bestpractices.dev/en/projects/7861"><img src="https://img.shields.io/cii/level/7861?label=openssf%20best%20practices&amp;color=2340b900&amp;cacheSeconds=60" alt="Practices" class="inline"/></a></p>
<h1><a class="anchor" id="overview"></a> Overview</h1>
<ul>
<li><a class="el" href="#synopsis">Synopsis</a></li>
<li><a class="el" href="#notables">Notables</a></li>
<li><a class="el" href="#cross-platform-compatibility">Cross-platform compatibility</a><ul>
<li><a class="el" href="#system-loggers">System Loggers</a></li>
<li><a class="el" href="#c---compatibility">C++ compatibility</a></li>
<li><a class="el" href="#language-bindings">Language Bindings</a></li>
</ul>
</li>
<li><a class="el" href="#an-example">An example</a></li>
<li><a class="el" href="#building-from-source">Building from source</a><ul>
<li><a class="el" href="#unix-makefile">Unix Makefile</a><ul>
<li><a class="el" href="#unix-makefile-envvars">Environment Variables</a></li>
<li><a class="el" href="#unix-makefile-recipes">Recipes</a></li>
</ul>
</li>
<li><a class="el" href="#visual-studio-code">Visual Studio Code</a><ul>
<li><a class="el" href="#vs-code-build-tasks">Build Tasks</a></li>
</ul>
</li>
<li><a class="el" href="#visual-studio-2022">Visual Studio 2022</a><ul>
<li><a class="el" href="#ms-build-tools">MSBuild</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="el" href="#dig-in">Dig in</a><ul>
<li><a class="el" href="#gnu-global">GNU Global</a></li>
</ul>
</li>
<li><a class="el" href="#sast-tools">SAST Tools</a></li>
<li><a class="el" href="#other-tools">Other Tools</a></li>
</ul>
<h1><a class="anchor" id="synopsis"></a> Synopsis</h1>
<p>libsir is a cross-platform, thread-safe logging library written in C (<em>ISO/IEC 9899:2011 C11</em>) that is designed to simplify and streamline the generation and distribution of human-readable information in software.</p>
<p>Using libsir, you can make a single call that simultaneously sends information to multiple destinations, <em>each with their own individual preference for format and levels</em>.</p>
<p>Each 'level' or 'priority' of output can be visually styled however you wish for <code>stdio</code> destinations. This allows for immediate visual confirmation that a message appeared in the terminal that you should pay attention to, while less pressing information is more subtle in appearance.</p>
<div class="image">
<img src="libsir-alpha.png" alt=""/>
<div class="caption">
libsir visual graph</div></div>
    <h1><a class="anchor" id="notables"></a> Notables</h1>
<ul>
<li>No dependencies (other than <code>libc</code> and <code>pthreads</code>). On Windows, libsir uses the native synchronization API.</li>
<li>Accompanied by a robust test suite to ensure dependable behavior, even if you make modifications to the source.</li>
<li>Won't fail silently&mdash;C library or platform level errors are captured and stored for posterity, on a per-thread basis. The <em>function, file, and line number from which it originated</em> are also captured. Additionally, libsir defines its own set of error messages to aid in troubleshooting.</li>
<li>Hardened&mdash;every function contains sanity checks for internal state as well as arguments passed in through the external interfaces. libsir's standard make recipes use <em>‑Wall ‑Wextra ‑Wpedantic</em> (and pass with <em>‑Wmissing‑prototypes ‑Wdouble‑promotion ‑Wfloat‑conversion ‑Wmissing‑declarations ‑Wswitch‑enum ‑Wformat‑nonliteral ‑Wformat‑truncation ‑Wbad‑function‑cast ‑Wextra‑semi‑stmt</em>, too.)</li>
<li><a href="https://libsir.rml.dev">Full documentation</a>, thanks to Doxygen.</li>
<li>Lightweight&mdash;the shared library comes in at around 70&#160;KiB, and the static library around 50&#160;KiB.</li>
</ul>
<h1><a class="anchor" id="cross-platform-compatibility"></a> Cross-platform compatibility</h1>
<p>At this time, libsir is supported (<em>that is, it compiles and passes the test suites</em>) on at least the following operating system and toolchain combinations:</p>
<table class="markdownTable">
<tr class="markdownTableHead">
<th class="markdownTableHeadRight">System   </th><th class="markdownTableHeadLeft">Toolchain    </th></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyRight"><b>Linux</b>&#160;≳2.6.32<br  />
(glibc&#160;≳2.4, musl&#160;≳1.2.3, uClibc‑ng&#160;≳1.0.43)   </td><td class="markdownTableBodyLeft"><b>GCC</b>&#160;(4.4.7&#160;‑&#160;15.0.1),&#160; <b>Clang</b>&#160;(3.8&#160;‑&#160;20.1.1),&#160; <b>Oracle&#160;Studio&#160;C/C++</b>&#160;(≳12.6),&#160; <b>Circle</b>&#160;(1.0.0‑210&#160;‑&#160;1.0.0‑226),&#160; <b>IBM&#160;Advance&#160;Toolchain</b>&#160;(14&#160;‑&#160;17),&#160; <b>IBM&#160;XL&#160;C/C++</b>&#160;(16.1.1.2&#160;‑&#160;16.1.1.15),&#160; <b>IBM&#160;Open&#160;XL&#160;C/C++</b>&#160;(17.1.1&#160;‑&#160;17.1.1.2),&#160; <b>NVIDIA&#160;HPC&#160;SDK&#160;C/C++</b>&#160;(23.5&#160;‑&#160;25.3),&#160; <b>Arm&#160;HPC&#160;C/C++</b>&#160;(22.1&#160;‑&#160;24.10.1),&#160; <b>DMD&#160;ImportC</b>&#160;(2.104.2&#160;‑&#160;2.111.0),&#160; <b>AMD&#160;Optimizing&#160;C/C++</b>&#160;(4.0.0&#160;‑&#160;5.0.0),&#160; <b>Intel&#160;oneAPI&#160;DPC++/C++</b>&#160;(2023.1&#160;‑&#160;2025.1.0),&#160; <b>Open64</b>&#160;(5,&#160;AMD&#160;4.5.2.1),&#160; <b>Intel&#160;C++&#160;Compiler&#160;Classic</b>&#160;(2021.9.0&#160;‑&#160;2021.10.0),&#160; <b>Portable&#160;C&#160;Compiler</b>&#160;(1.2.0.DEVEL‑20230730),&#160; <b>Kefir</b>&#160;(≳0.3.0),&#160; <b>Chibicc</b>&#160;(2020.12.6),&#160; <b>CompCert&#160;C</b>&#160;(3.11&#160;‑&#160;3.15,&#160;no‑TLS),&#160; <b>Chamois‑CompCert&#160;C</b>&#160;(3.14‑20231130+,&#160;TLS),&#160; <b>МЦСТ&#160;LCC</b>&#160;(1.25&#160;‑&#160;1.29)    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyRight"><b>Android</b>&#160;≳5   </td><td class="markdownTableBodyLeft"><b>Android&#160;NDK</b>&#160;(r25c&#160;‑&#160;r28)    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyRight"><b>QNX</b>&#160;8.0   </td><td class="markdownTableBodyLeft"><b>QCC</b>&#160;(GCC&#160;12.2)    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyRight"><b>IBM AIX</b>&#160;7.2,&#160;7.3   </td><td class="markdownTableBodyLeft"><b>GCC</b>&#160;(8.3&#160;‑&#160;12.3),&#160; <b>Clang</b>&#160;(18.1.2&#160;‑&#160;20.1.0),&#160; <b>IBM&#160;XL&#160;C/C++</b>&#160;(16.1.0.3&#160;‑&#160;16.1.0.20),&#160; <b>IBM&#160;Open&#160;XL&#160;C/C++</b>&#160;(17.1.1.1&#160;‑&#160;17.1.3.1)    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyRight"><b>IBM i</b>&#160;(<b>PASE</b>)&#160;7.5   </td><td class="markdownTableBodyLeft"><b>GCC</b>&#160;(10.3&#160;‑&#160;10.5),&#160; <b>IBM&#160;XL&#160;C/C++</b>&#160;(16.1.0.15&#160;‑&#160;16.1.0.20)    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyRight"><b>macOS</b>&#160;≳10.15   </td><td class="markdownTableBodyLeft"><b>Xcode</b>&#160;(11.7&#160;‑&#160;16.3),&#160; <b>GCC</b>&#160;(10.4&#160;‑&#160;14.2),&#160; <b>Clang</b>&#160;(11.0.3&#160;‑&#160;19.1.7),&#160; <b>DMD&#160;ImportC</b>&#160;(2.105.0&#160;‑&#160;2.111.0),&#160; <b>Intel&#160;C++&#160;Compiler&#160;Classic</b>&#160;(2021.9.0&#160;‑&#160;2021.10.0)    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyRight"><b>Windows</b>&#160;≳10,&#160;11   </td><td class="markdownTableBodyLeft"><b>Microsoft&#160;Visual&#160;C/C++</b>&#160;(17.6&#160;‑&#160;17.13.5),&#160; <b>Clang‑CL</b>&#160;(16.0.6&#160;‑&#160;20.1.1),&#160; <b>GCC‑MinGW</b>&#160;(12.2.1&#160;‑&#160;14.2.1),&#160; <b>LLVM‑MinGW</b>&#160;(15.0&#160;‑&#160;20.1.1),&#160; <b>Embarcadero&#160;C++</b>&#160;(7.20&#160;‑&#160;7.70),&#160; <b>OrangeC</b>&#160;(≳6.71.10)    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyRight"><b>Cygwin</b>&#160;3.4   </td><td class="markdownTableBodyLeft"><b>GCC</b>&#160;(11.2&#160;‑&#160;15.0)    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyRight"><b>FreeBSD</b>&#160;≳11.3   </td><td class="markdownTableBodyLeft"><b>GCC</b>&#160;(11.4&#160;‑&#160;14.2),&#160; <b>Clang</b>&#160;(10&#160;‑&#160;19.1.7),&#160; <b>DMD&#160;ImportC</b>&#160;(2.105.0&#160;‑&#160;2.111.0)    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyRight"><b>NetBSD</b>&#160;9.2,&#160;10   </td><td class="markdownTableBodyLeft"><b>GCC</b>&#160;(7.5&#160;‑&#160;14.2),&#160; <b>Clang</b>&#160;(15.0.7&#160;‑&#160;18.1.8)    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyRight"><b>OpenBSD</b>&#160;7.3   </td><td class="markdownTableBodyLeft"><b>GCC</b>&#160;(11.2),&#160; <b>Clang</b>&#160;(13&#160;‑&#160;18.1.8),&#160; <b>DMD&#160;ImportC</b>&#160;(2.106.0&#160;‑&#160;2.111.0)    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyRight"><b>DragonFly</b>&#160;<b>BSD</b>&#160;6.4   </td><td class="markdownTableBodyLeft"><b>GCC</b>&#160;(8.3&#160;‑&#160;13),&#160; <b>Clang</b>&#160;(10.0.1&#160;‑&#160;17.0.6)    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyRight"><b>GNU/Hurd</b>   </td><td class="markdownTableBodyLeft"><b>GCC</b>&#160;(9.5&#160;‑&#160;13.2),&#160; <b>Clang</b>&#160;(9.0.1&#160;‑&#160;13.0.1)    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyRight"><b>Haiku</b>&#160;R1b4   </td><td class="markdownTableBodyLeft"><b>GCC</b>&#160;(11.2&#160;‑&#160;13.3),&#160; <b>Clang</b>&#160;(12.0.1&#160;‑&#160;20.1.0)    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyRight"><b>Solaris</b>&#160;11.4   </td><td class="markdownTableBodyLeft"><b>GCC</b>&#160;(10.3&#160;‑&#160;11.2),&#160; <b>Clang</b>&#160;(6&#160;‑&#160;18.1.8),&#160; <b>Oracle&#160;Studio&#160;C/C++</b>&#160;(≳12.6)    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyRight"><b>illumos</b>   </td><td class="markdownTableBodyLeft"><b>GCC</b>&#160;(7.5&#160;‑&#160;14.2),&#160; <b>Clang</b>&#160;(15.0.7&#160;‑&#160;19.1.7),&#160; <b>Oracle&#160;Studio&#160;C/C++</b>&#160;(≳12.6)    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyRight"><b>SerenityOS</b>   </td><td class="markdownTableBodyLeft"><b>GCC</b>&#160;(13.1)    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyRight"><b>Managarm</b>   </td><td class="markdownTableBodyLeft"><b>GCC</b>&#160;(14.2)    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyRight"><b>WebAssembly/JS</b>   </td><td class="markdownTableBodyLeft"><b>Emscripten</b>&#160;(3.1.45&#160;‑&#160;4.0.5),&#160; <b>Node.js</b>&#160;(20.5.0&#160;‑&#160;23.10.0)   </td></tr>
</table>
<ul>
<li>libsir is known to work on most common (and many uncommon) architectures. It has been built and tested on <b>Intel</b> (x86_64, i686, x32), <b>ARM</b> (ARMv6, ARMv7HF, ARMv8‑A), <b>POWER</b> (PowerPC, PPC64, PPC64le), <b>MIPS</b> (MIPS64, MIPS32, 74Kc), <b>SPARC</b> (SPARC64, V8, LEON3), <b>z/Architecture</b> (S390X), <b>SuperH</b> (SH‑4A), <b>RISC‑V</b> (RV32, RV64), <b>OpenRISC</b> (OR1200), <b>Kalray MPPA®</b> (Coolidge™, KVX), <b>МЦСТ Эльбрус</b> (E2K), and <b>m68k</b> (ColdFire, 68020+).</li>
<li>This table only lists toolchains that have been tested and is by no means exhaustive&mdash;newer (or older) versions are likely to work without fanfare. In fact, if it <em>doesn't</em> work on your machine, it's probably a bug.</li>
</ul>
<h2><a class="anchor" id="system-loggers"></a> System Loggers</h2>
<p>libsir currently supports the following system logging facilities:</p>
<table class="markdownTable">
<tr class="markdownTableHead">
<th class="markdownTableHeadRight"><b>Log&#160;Facility</b>   </th><th class="markdownTableHeadLeft"><b>System</b>   </th><th class="markdownTableHeadLeft"><b>Description</b>    </th></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyRight"><b>Event&#160;Log</b>   </td><td class="markdownTableBodyLeft">Windows   </td><td class="markdownTableBodyLeft">System log viewable with <b>Event Viewer</b>    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyRight"><b>os_log</b>   </td><td class="markdownTableBodyLeft">macOS   </td><td class="markdownTableBodyLeft">System log viewable with <b>Console</b> (<em>or <code>log</code></em>)    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyRight"><b>syslog</b>   </td><td class="markdownTableBodyLeft">(<em>many</em>)   </td><td class="markdownTableBodyLeft">BSD-style system logging via <code>syslog()</code> (<em>local only</em>)   </td></tr>
</table>
<h2><a class="anchor" id="c---compatibility"></a> C++ compatibility</h2>
<ul>
<li><p class="startli">A C++20 <a href="https://github.com/aremmell/libsir/blob/master/include/sir.hh">header-only wrapper</a> is available which allows for easy integration with C++ projects, including optional support for popular formatting libraries:</p>
<table align="center">
<tr>
<td align="center"><center>&#160;<a href="https://fmt.dev"><b>{fmt}</b></a>&#160;</center> </td><td align="center"><center>&#160;<a href="https://en.cppreference.com/w/cpp/utility/format/format"><b>std</b>::<b>format</b></a>&#160;</center> </td><td align="center"><center>&#160;<a href="https://www.boost.org/libs/format"><b>Boost</b>.<b>Format</b></a>&#160;</center> </td><td align="center"><center>&#160;<a href="https://cplusplus.com/reference/istream/iostream"><b>std</b>::<b>iostream</b></a>&#160;</center>   </td></tr>
</table>
</li>
</ul>
<h2><a class="anchor" id="language-bindings"></a> Language Bindings</h2>
<ul>
<li><p class="startli"><a href="https://github.com/aremmell/libsir/tree/master/bindings">Bindings</a> for scripting tools and other high-level programming languages are available, including support for:</p>
<table align="center">
<tr>
<td align="center"><center>&#160;<a href="https://www.softintegration.com"><b>Ch</b></a>&#160;</center> </td><td align="center"><center>&#160;<a href="https://www.python.org"><b>Python</b></a>&#160;</center>   </td></tr>
</table>
</li>
</ul>
<h1><a class="anchor" id="an-example"></a> An example</h1>
<p>Some sample terminal output from libsir demonstrating the default text styling settings for stdio (<em>note that this is just a sample; libsir supports 4, 8, and 24-bit color modes, so a virtually limitless number of configurations are possible</em>):</p>
<div class="image">
<img src="sample-terminal.png" alt=""/>
<div class="caption">
sample terminal output</div></div>
    <p>This output is from the <code>example</code> application, whose source code can be located in the <a href="https://github.com/aremmell/libsir/tree/master/example">example</a> directory. If you're curious about a very basic implementation of libsir in a practical context, that's a good place to start.</p>
<p><b>Coming soon:</b> A C++20 version of the example program.</p>
<h1><a class="anchor" id="building-from-source"></a> Building from source</h1>
<p>There are several options available for building libsir from source:</p>
<h2><a class="anchor" id="unix-makefile"></a> Unix Makefile</h2>
<p>The Makefiles are compatible with <b>GNU Make</b> version <b>3.81</b> and later (<b>4.4</b> <em>recommended</em>) and support both native and cross-compilation builds on most Unix-like operating systems: AIX, Solaris, illumos, Linux, macOS, Cygwin, BSD, GNU/Hurd, Haiku, QNX, etc.</p>
<h3><a class="anchor" id="unix-makefile-envvars"></a> Environment variables</h3>
<p>A number of environment variables are available which affect the way in which libsir and its various build artifacts are created (<em>e.g., turning off optimizations and enabling debug symbols</em>). Information about these variables and how to use them with GNU make can be found in the <a href="https://libsir.rml.dev/config.html">online documentation</a>.</p>
<h3><a class="anchor" id="unix-makefile-recipes"></a> Recipes</h3>
<table class="markdownTable">
<tr class="markdownTableHead">
<th class="markdownTableHeadRight">Recipe Type   </th><th class="markdownTableHeadCenter">Command   </th><th class="markdownTableHeadLeft">&#160;&#160;&#160;&#160;Output file(s)    </th></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyRight">Test&#160;suite (C)   </td><td class="markdownTableBodyCenter"><code>make tests</code>   </td><td class="markdownTableBodyLeft"><ul>
<li>
<em>build/bin/sirtests[.exe]</em></li>
</ul>
</td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyRight">Test&#160;suite (C++)   </td><td class="markdownTableBodyCenter"><code>make tests++</code>   </td><td class="markdownTableBodyLeft"><ul>
<li>
<em>build/bin/sirtests++[.exe]</em></li>
</ul>
</td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyRight">Example&#160;app   </td><td class="markdownTableBodyCenter"><code>make example</code>   </td><td class="markdownTableBodyLeft"><ul>
<li>
<em>build/bin/sirexample[.exe]</em></li>
</ul>
</td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyRight">Static&#160;library   </td><td class="markdownTableBodyCenter"><code>make static</code>   </td><td class="markdownTableBodyLeft"><ul>
<li>
<em>build/lib/libsir_s.a</em></li>
</ul>
</td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyRight">nShared&#160;library   </td><td class="markdownTableBodyCenter"><code>make shared</code>   </td><td class="markdownTableBodyLeft"><ul>
<li>
<em>build/lib/libsir.so</em></li>
</ul>
</td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyRight">Installation   </td><td class="markdownTableBodyCenter"><code>make install</code>   </td><td class="markdownTableBodyLeft"><ul>
<li>
<em>$PREFIX/lib/libsir_s.a</em></li>
<li>
<em>$PREFIX/lib/libsir.so</em></li>
<li>
<em>$PREFIX/include/sir.h</em></li>
<li>
<em>$PREFIX/include/sir/*.h</em></li>
</ul>
</td></tr>
</table>
<ul>
<li>See the <a href="https://github.com/aremmell/libsir/blob/master/.gitlab-ci.yml">CI configuration file</a> for practical examples.</li>
</ul>
<h2><a class="anchor" id="visual-studio-code"></a> Visual Studio Code</h2>
<p>A VS Code workspace file is located in the root of the repository (<code>sir.code-workspace</code>). Build tasks are only configured for macOS and Linux. On other platforms, use the integrated terminal to run GNU <a class="el" href="#unix-makefile">`make`</a> manually.</p>
<h3><a class="anchor" id="vs-code-build-tasks"></a> Build Tasks</h3>
<p>To run a task, open the command list (<kbd>&amp;#8984;</kbd> + <kbd>&amp;#8679;</kbd> + <kbd>P</kbd> on macOS, <kbd>&amp;#8963;</kbd> + <kbd>&amp;#8679;</kbd> + <kbd>P</kbd> on Linux), then start typing <code>"run task"</code> until you see <code>"Tasks: Run Task"</code>. Click the item or press the key combination listed next to it. You should then see a drop-down menu containing all of the build tasks for libsir, which are listed here:</p>
<table class="markdownTable">
<tr class="markdownTableHead">
<th class="markdownTableHeadRight">Build Task   </th><th class="markdownTableHeadLeft">Description    </th></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyRight">Clean   </td><td class="markdownTableBodyLeft">Deletes all intermediate files and previously compiled binaries.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyRight">Static Library   </td><td class="markdownTableBodyLeft">Compiles libsir as a static library.    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyRight">Static Library [DBG]   </td><td class="markdownTableBodyLeft">Compiles libsir as a static library with debug symbols.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyRight">Shared Library   </td><td class="markdownTableBodyLeft">Compiles libsir as a shared library.    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyRight">Shared Library [DBG]   </td><td class="markdownTableBodyLeft">Compiles libsir as a shared library with debug symbols.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyRight">C Test Suite   </td><td class="markdownTableBodyLeft">Compiles the C test suite.    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyRight">C Test Suite [DBG]   </td><td class="markdownTableBodyLeft">Compiles the C test suite with debug symbols.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyRight">C++ Test Suite   </td><td class="markdownTableBodyLeft">Compiles the C++ test suite.    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyRight">C++ Test Suite [DBG]   </td><td class="markdownTableBodyLeft">Compiles the C++ test suite with debug symbols.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyRight">C Example App   </td><td class="markdownTableBodyLeft">Compiles the C sample application.   </td></tr>
</table>
<p>The VS Code build tasks execute <code>make</code> under the hood&mdash;the non-debug tasks map directly to the <a class="el" href="#unix-makefile-recipes">recipes</a> listed under Unix Makefile; the debug tasks utilize libsir's custom <a class="el" href="#unix-makefile-envvars">environment variables</a> to control the build process.</p>
<h2><a class="anchor" id="visual-studio-2022"></a> Visual Studio 2022</h2>
<p>A Visual Studio 2022 solution containing appropriate project files can be found in the <a href="https://github.com/aremmell/libsir/tree/master/msvs">msvs</a> directory. Tested on Windows 11 (<em>x86, x64, and Arm64</em>) with Visual Studio 17.6+. See the <a href="https://github.com/aremmell/libsir/tree/master/msvs/README.md">README</a> for more information.</p>
<h3><a class="anchor" id="ms-build-tools"></a> MSBuild</h3>
<p>Visual Studio is technically not required in order to build the Visual Studio 2022 solution; this may also be accomplished using "Build Tools for Visual Studio 2022" (<a href="https://aka.ms/vs/17/release/vs_BuildTools.exe">download</a>, <a href="https://learn.microsoft.com/en-us/visualstudio/msbuild/msbuild-command-line-reference?view=vs-2022">reference</a>). This is a stand-alone toolchain that does <em>not</em> require Visual Studio 2022 and includes compilers and MSBuild.</p>
<p><b>Using MSBuild from the command-line</b></p>
<p>Using MSBuild is pretty straightforward. Start a Developer Command Prompt, and then just supply the path to the <code>.sln</code> file, task (<em>e.g. <code>build</code></em>), configuration (<em>e.g. <code>release</code></em>), and platform (<em>e.g. <code>x64</code></em>). Here's an example that builds libsir in release mode for x86_64 when executed from the root of the libsir repository:</p>
<div class="fragment"><div class="line">MSBuild .\msvs\libsir.sln -t:Rebuild -p:Configuration=Release -p:Platform=x64</div>
</div><!-- fragment --><h1><a class="anchor" id="dig-in"></a> Dig in</h1>
<p>If you are genuinely interested in utilizing libsir, you are encouraged to read the <a href="https://libsir.rml.dev">full online documentation</a> to get a better understanding of the library's capabilities and interfaces.</p>
<p>Suggested initial sections:</p><ul>
<li><a href="https://libsir.rml.dev/group__publicfuncs.html">Public Functions</a></li>
<li><a href="https://libsir.rml.dev/group__publictypes.html">Public Types</a></li>
<li><a href="https://libsir.rml.dev/config.html">Configuration</a></li>
<li><a href="https://libsir.rml.dev/testsuite.html">Test suite</a></li>
</ul>
<h2><a class="anchor" id="gnu-global"></a> GNU Global</h2>
<ul>
<li><a href="https://libsir.gitlab.io/libsir">A GNU Global-generated tagged and cross-referenced hypertext source code listing is available.</a></li>
<li>This tagged listing is a valuable aid for new developers seeking an understanding of the libsir source code.</li>
</ul>
<h1><a class="anchor" id="sast-tools"></a> SAST Tools</h1>
<p>The developers are obsessed with the quality, reliability, and correctness of libsir.</p>
<p>The following <b>SAST</b> (<em>static application</em>/*analysis security*/*software testing*) and dynamic verification tools are used&mdash;on <b>every commit</b>&mdash;as part of our comprehensive <a href="https://gitlab.com/libsir/libsir/-/pipelines">continuous integration</a> testing process:</p>
<table class="markdownTable">
<tr class="markdownTableHead">
<th class="markdownTableHeadRight">Tool   </th><th class="markdownTableHeadLeft">Usage    </th></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyRight"><a href="https://pvs-studio.com/pvs-studio/?utm_source=website&amp;utm_medium=github&amp;utm_campaign=open_source"><b>PVS-Studio</b></a>   </td><td class="markdownTableBodyLeft">Static analysis tool for C, C++, C#, and Java code    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyRight"><a href="https://clang-analyzer.llvm.org/">Clang Analyzer</a>, <a href="https://github.com/google/sanitizers">Sanitizers</a>   </td><td class="markdownTableBodyLeft">Static and dynamic analysis tools for C, C++, and Objective-C code    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyRight"><a href="https://coveralls.io/github/aremmell/libsir">Coveralls</a>, <a href="https://gcovr.com/">gcovr</a>   </td><td class="markdownTableBodyLeft">Line-by-line test coverage reporting and statistical analysis    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyRight"><a href="https://scan.coverity.com/projects/aremmell-libsir">Coverity® Scan</a>   </td><td class="markdownTableBodyLeft">Find and fix defects in Java, C/C++, C#, JS, Ruby, and Python code    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyRight"><a href="https://cppchecksolutions.com/">Cppcheck</a>   </td><td class="markdownTableBodyLeft">Static analysis tool for C and C++ code    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyRight"><a href="https://github.com/johnsonjh/duma">DUMA</a>   </td><td class="markdownTableBodyLeft">Detect Unintended Memory Access, a memory debugger    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyRight"><a href="https://dwheeler.com/flawfinder/">Flawfinder</a>   </td><td class="markdownTableBodyLeft">Scans C and C++ source code for potential security weaknesses    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyRight"><a href="https://gcc.gnu.org/onlinedocs/gcc/Static-Analyzer-Options.html">GCC Static Analyzer</a>   </td><td class="markdownTableBodyLeft">Coverage-guided symbolic execution static analyzer for C code    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyRight"><a href="https://www.gnu.org/software/cppi/">GNU Cppi</a>   </td><td class="markdownTableBodyLeft">C preprocessor directive linting, indenting, and regularization    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyRight"><a href="https://www.gnu.org/software/global/">GNU Global</a>   </td><td class="markdownTableBodyLeft">Source code indexing and tagging system    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyRight"><a href="https://github.com/cisco/OpenOSC">OpenOSC</a>   </td><td class="markdownTableBodyLeft">Object size checking library to detect buffer overflows in C/C++ code    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyRight"><a href="https://www.oracle.com/application-development/developerstudio/">Oracle Developer Studio</a>   </td><td class="markdownTableBodyLeft">Performance, security, and thread analysis tools for C, C++, and Fortran    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyRight"><a href="https://api.reuse.software/info/github.com/aremmell/libsir">REUSE</a>   </td><td class="markdownTableBodyLeft">Verifies compliance with the <a href="https://reuse.software/">REUSE</a> licensing guidelines    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyRight"><a href="https://semgrep.dev/">Semgrep</a>   </td><td class="markdownTableBodyLeft">A fast, open-source, static analysis engine for many languages    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyRight"><a href="https://sonarcloud.io/project/overview?id=aremmell_libsir">SonarCloud</a>   </td><td class="markdownTableBodyLeft">Cloud-based code quality and security analysis tools    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyRight"><a href="https://valgrind.org/">Valgrind</a>   </td><td class="markdownTableBodyLeft">Tools for memory debugging, memory leak detection, and profiling    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyRight"><a href="https://learn.microsoft.com/en-us/cpp/code-quality/">Visual Studio Code Analyzer</a>   </td><td class="markdownTableBodyLeft">Tools to analyze and improve C/C++ source code quality   </td></tr>
</table>
<h1><a class="anchor" id="other-tools"></a> Other Tools</h1>
<p>Additional tools used for libsir development and testing include:</p>
<table class="markdownTable">
<tr class="markdownTableHead">
<th class="markdownTableHeadRight">Tool   </th><th class="markdownTableHeadLeft">Usage    </th></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyRight"><a href="http://www.cprover.org/cbmc/">CBMC</a>, <a href="http://esbmc.org/">ESBMC</a>   </td><td class="markdownTableBodyLeft">Bounded Model Checkers for C and C++ programs    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyRight"><a href="https://drmemory.org/">Dr. Memory</a>   </td><td class="markdownTableBodyLeft">Memory debugging tool for Windows, Linux, macOS, and Android    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyRight"><a href="https://github.com/tmatis/funcheck">Funcheck</a>   </td><td class="markdownTableBodyLeft">A tool for checking function call return protections    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyRight"><a href="https://frama-c.com/">Frama-C</a>   </td><td class="markdownTableBodyLeft">Framework for Modular Analysis of C programs    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyRight"><a href="https://www.intel.com/content/www/us/en/developer/tools/oneapi/vtune-profiler.html">Intel® VTune™ Profiler</a>   </td><td class="markdownTableBodyLeft">Performance analysis and profiling tools for Intel systems    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyRight"><a href="https://lukestackwalker.sf.net/">Luke Stackwalker</a>   </td><td class="markdownTableBodyLeft">Sampling C/C++ code profiler for Microsoft Windows    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyRight"><a href="https://man.netbsd.org/lint.1">NetBSD lint(1)</a>   </td><td class="markdownTableBodyLeft">A C (C90/C99/C11/C17/C23) program verifier    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyRight"><a href="https://www.teamblue.unicomsi.com/products/purifyplus/">PurifyPlus™</a>   </td><td class="markdownTableBodyLeft">Run-time analysis tools for application reliability and performance    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyRight"><a href="https://www.shellcheck.net/">ShellCheck</a>   </td><td class="markdownTableBodyLeft">A static analysis tool for Unix shell scripts    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyRight"><a href="https://repo.or.cz/w/smatch.git">Smatch</a>   </td><td class="markdownTableBodyLeft">Smatch (Source Matcher) is a static analysis tool for C code    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyRight"><a href="https://www.softintegration.com/">SoftIntegration Ch</a>   </td><td class="markdownTableBodyLeft">C/C++ interpreter and interactive platform for scientific computing    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyRight"><a href="http://www.codersnotes.com/sleepy/">Very Sleepy</a>   </td><td class="markdownTableBodyLeft">Sampling CPU profiler for Microsoft Windows applications    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyRight"><a href="https://github.com/SX-Aurora/Vftrace">Vftrace</a>   </td><td class="markdownTableBodyLeft">A performance profiling library with a focus on HPC applications   </td></tr>
</table>
</div></div><!-- PageDoc -->
<a href="doxygen_crawl.html"></a>
</div><!-- contents -->
</div><!-- doc-content -->
<!-- HTML footer for doxygen 1.9.7-->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="footer">Generated by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.13.2 </li>
  </ul>
</div>
</body>
</html>
